Taskbase
API docs by Redocly

Taskbase Feedback API for Bitmark (0.4.0)

Download OpenAPI specification:Download

Kristian: kristian@taskbase.com URL: https://www.taskbase.com/contact License: Copyright Taskbase

Introduction

This document will be steadily extended and updated to reflect new functionality of the API while constantly ensuring backwards compatibility with previous versions.

We follow Semantic Versioning. You can see all versions in our changelog.

Feedback

Endpoints for working with feedback.

Computes feedback for the bit

This operation gives its consumers access to our formative feedback. The bit that is supplied in the request is required for context and shall be included on every request. This way we avoid any synchronization problems that otherwise will occur, where feedback was returned based on some outdated state of the bit.

For identifying inputs belonging to the same bit, the feedbackId field on the FeedbackEngine object itself is of importance. This field shall represent the identifier of the bit s.t. existing feedback can be re-used. When this field remains the same across requests but other bit fields change, then for some existing bit t the fields will be updated and the feedback will be generated based on previously seen inputs and created feedback belonging to that bit b (*). On the other side, when the value for the feedbackId field was not yet seen by the system, a new bit b' will be created. Consequently, there are no existing inputs and thus also no feedback assigned that belong to the bit b' yet. Therefore, consider only changing the identifier when you wish to create a brand new bit.

(*) This does only hold as long as the types are the same. When for some request the bit type is different to what already exists due to previous requests, then an error will be returned.

Further, as of now, bits are always created within the default tenant. There is no way currently to create a bit in a different tenant through the API.

Important note on bit updates: each time a bit gets changed on the consumer's system, one should assume those changes impact the feedback. Hence, we advise in such situations to test the feedback and create new inputs, as well as potentially re-assign existing feedback for previous inputs, in order to adjust the feedback to those changes. Without those measures, generated feedback may not be accurate anymore.

Authorizations:
BearerAuthentication
Request Body schema: application/json
type
required
string

Defines the type of bit. Can be used by deserialization tools to instanciate the correct sub-type.

format
required
string

Allowed values: text , bitmark-- , bitmark+ , bitmark++

required
object
object
instruction
required
string
sampleSolution
required
string

A sample answer to the problem statement that is considered being correct.

required
object

An answer input field of the problem statement.

object

A media file of the task.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "essay",
  • "format": "string",
  • "feedbackEngine": {
    },
  • "meta": {
    },
  • "instruction": "string",
  • "sampleSolution": "string",
  • "answer": {
    },
  • "resource": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "essay",
  • "format": "string",
  • "feedbackEngine": {
    },
  • "meta": {
    },
  • "instruction": "string",
  • "feedback": [
    ],
  • "sampleSolution": "string",
  • "answer": {
    },
  • "resource": {
    }
}

The Bit Types

string (BitType)
Enum: "essay" "cloze" "multiple-choice-text"

Defines the type of bit. Can be used by deserialization tools to instanciate the correct sub-type.

"essay"
Type Description
essay Bit with a free text input field.
cloze Bit with a given text that contains blanks to be filled out.
multiple-choice-text Defines a multiple choice quiz where the choices are embedded in a text.

The Bit Model

type
required
string

Defines the type of bit. Can be used by deserialization tools to instanciate the correct sub-type.

format
required
string

Allowed values: text , bitmark-- , bitmark+ , bitmark++

required
object
object
instruction
required
string
required
Array of objects (EssayBitFeedbackItem)
sampleSolution
required
string

A sample answer to the problem statement that is considered being correct.

required
object

An answer input field of the problem statement.

object

A media file of the task.

Example
{
  • "type": "essay",
  • "format": "string",
  • "feedbackEngine": {
    },
  • "meta": {
    },
  • "instruction": "string",
  • "feedback": [
    ],
  • "sampleSolution": "string",
  • "answer": {
    },
  • "resource": {
    }
}

The Error Response Model

message
required
string

Holds more detailed information on the root cause of the problem.

type
required
string
Enum: "REQUEST_SCHEMA_MALFORMED" "INVALID_TOKEN" "MISSING_PERMISSIONS" "INVALID_PARAMETER" "WRONG_TASK_TYPE_FOR_UPSERT" "INTERNAL"

Errors the API may respond with. For further explanations check the error table.

{
  • "message": "computeFeedback.feedbackEngine.userId must not be null.",
  • "type": "REQUEST_SCHEMA_MALFORMED"
}

Error Types

The API returns the following custom errors.

Type Description
REQUEST_SCHEMA_MALFORMED The request schema is malformed. The message field includes further details on what is wrong or missing.
INVALID_TOKEN The provided bearer token is invalid.
MISSING_PERMISSIONS The application does not have permissions for requesting this action.
INVALID_PARAMETER Some parameter validation failed. The message field includes further details on what is wrong.
WRONG_TASK_TYPE_FOR_UPSERT A bit with the specified ID already exists but does not match the bit type that is specified in the request.
INTERNAL Internal Server error. The message field includes an identifier which should be included when contacting our support.